Skip to main content

IIH Essentials Migration Guide - SQL Connector 2.x.x

Overview​

This guide provides step-by-step instructions for migrating your Siemens IIH Essentials configuration when upgrading from SQL Connector version 1.x.x to 2.x.x.

Breaking Changes Summary​

Starting with version 2.0.0, the SQL Connector introduces a breaking change in how datapoint definitions are named in meta messages:

  • Previous behavior (1.x.x): Used database column names as datapoint definition names
  • New behavior (2.x.x): Uses Common Configurator Tag names as datapoint definition names

This change ensures compliance with payload standards where each metadata datapoint definition name must be unique within a connection.

Impact Assessment​

Who is Affected?​

Your IIH Essentials configuration will be affected if:

  • You have existing SQL Connector configurations in IIH Essentials
  • Your tag names differ from your database column names
  • Your applications depend on specific datapoint definition names

Who is NOT Affected?​

If your tag names and column names are identical, no migration may be required.

Affected vs. Not affected

Pre-Migration Checklist​

Before starting the migration process:

🛡️ Backup your IIH Essentials configuration and data
📝 Document current tag mappings - Record which tags are mapped to which database columns
🔍 Identify affected connections - List all SQL Connector connections in your IIH Essentials setup
⏰ Plan maintenance window - Schedule downtime for the migration process
🔄 Verify connector versions - Ensure you're upgrading to SQL Connector 2.0.0 or later

Migration Steps​

Step 1: Update SQL Connector​

  1. Download the latest SQL Connector version (2.x.x) from the Siemens Industrial Edge Hub
  2. Stop the existing SQL Connector application
  3. Uninstall the old version (1.x.x)
  4. Install the new version (2.x.x)
  5. Verify the installation is successful

Step 2: Review Tag Configuration​

  1. Access the Common Configurator for your SQL Connector
  2. Navigate to your database connection configuration
  3. Review each configured tag and note:
    • Tag name (as configured in Common Configurator)
    • Corresponding database column name
    • Any discrepancies between tag and column names

Tag to Column Name

Step 3: Update IIH Essentials Configuration​

For each affected asset in IIH Essentials:​

  1. Open IIH Essentials Web Interface
  2. Backup in Settings → Data Backup
  3. Navigate to Manage Data → Your Connector Asset
  4. Access the asset attributes that needs updating

Update Tag Mappings:​

  1. Locate assets with tags that have different names from their database columns, will be diconnected (marked with red cricle)
  2. Update the tag mapping of each affected attribute in IIH Essentials to match the new tag names, the new tag's mapping should be available within the connector tags.
  3. Save the configuration changes
Example Mapping Update

Before (using column names): SQL Connector/edge-test/id

{
    "name":"id",
    "id":"DP1",
    "dataType":"DWord",
    "accessMode":"rw",
    "valueRank":-3,
    "arrayDimensions":null,
    "acquisitionCycleInMs":3000,
    "acquisitionMode":"Newest"
}

Example of diconnected attributes

After (using tag names): SQL Connector/edge-test/id tag name

{
    "name":"id tag name",
    "id":"DP1",
    "dataType":"DWord",
    "accessMode":"rw",
    "valueRank":-3,
    "arrayDimensions":null,
    "acquisitionCycleInMs":3000,
    "acquisitionMode":"Newest"
}

Example of connected attributes

Step 4: Test the Configuration​

  1. Start the updated SQL Connector
  2. Verify data flow in IIH Essentials:
    • Check that data is being received correctly for each attribute.
    • Confirm data values match expectations
  3. Monitor for any log error messages in:
    • SQL Connector logs
    • IIH Essentials logs
    • Industrial Edge Management system logs

Step 5: Validate Migration​

Data Validation Checklist:​

  • All configured tags are receiving data
  • Data values are correct and match pre-migration values
  • No error messages in connector or IIH logs
  • All dependent applications are functioning correctly
  • Performance is as expected (or better due to optimizations)

Troubleshooting​

Common Issues and Solutions​

Issue: "Disconnected attributes" errors in IIH Essentials​

Solution: Verify that the tag mappings in IIH match exactly with the tag names configured in Common Configurator

Getting Help​

If you encounter issues during migration:

  1. Check logs in both SQL Connector and IIH Essentials
  2. Verify tag name consistency between Common Configurator and IIH Essentials
  3. Contact Siemens and Axtesys support with:
    • Connector and IIH Essentials version information
    • Error messages and logs
    • Description of your configuration setup